mcp-pacemaker 2.0.1 → 2.1.0

package/autostart/windows/register-task.ps1

@@ -6,13 +6,18 @@
   logon AND on workstation unlock (unlock covers sleep/wake, where logon never fires).
 .PARAMETER Port  Port to pass through to the supervisor (default 8791).
 .PARAMETER TaskName  Selected per-user task name (default McpPacemaker-<port>).
+.PARAMETER LauncherPath  Stable per-instance launcher, when using managed upgrades.
 .OUTPUTS
   Registration result.
 .EXAMPLE
   .\register-task.ps1 -Port 8791
 #>
 [CmdletBinding()]
-param([ValidateRange(1, 65535)][int]$Port = 8791, [string]$TaskName = "McpPacemaker-$Port")
+param(
+  [ValidateRange(1, 65535)][int]$Port = 8791,
+  [string]$TaskName = "McpPacemaker-$Port",
+  [string]$LauncherPath
+)
 
 $ErrorActionPreference = 'Stop'
 try {
@@ -21,6 +26,10 @@ try {
     throw 'Cache-backed npx roots cannot host autostart. Install in a durable root first.'
   }
   $vbs  = Join-Path $PSScriptRoot 'launcher.vbs'
+  if ($LauncherPath) {
+    $vbs = (Resolve-Path -LiteralPath $LauncherPath).Path
+    if ($vbs -match '["\r\n]') { throw 'Unsupported launcher path.' }
+  }
   $user = "$env:USERDOMAIN\$env:USERNAME"
 
   $svc = New-Object -ComObject Schedule.Service
@@ -48,7 +57,7 @@ try {
 
   $action = $def.Actions.Create(0)               # TASK_ACTION_EXEC
   $action.Path = 'wscript.exe'
-  $action.Arguments = "`"$vbs`" $Port"
+  $action.Arguments = if ($LauncherPath) { "`"$vbs`"" } else { "`"$vbs`" $Port" }
 
   $def.Principal.UserId = $user
   $def.Principal.LogonType = 3                    # interactive token (no stored password)

package/bin/account-task-adapter.mjs

@@ -0,0 +1,47 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export function windowsArgument(value) {
+  return `"${String(value).replace(/(\\*)"/g, '$1$1\\"').replace(/(\\+)$/, '$1$1')}"`;
+}
+
+export class AccountTaskAdapter {
+  constructor({ taskPath, targetSid, powershell, run = execFileSync }) {
+    this.taskPath = taskPath;
+    this.targetSid = targetSid;
+    this.powershell = powershell;
+    this.run = run;
+  }
+
+  call(action, input = {}) {
+    if (!this.powershell || !existsSync(this.powershell)) throw new Error('A verified absolute PowerShell toolchain is required.');
+    const script = fileURLToPath(new URL('../autostart/windows/account-task.ps1', import.meta.url));
+    const env = { ...process.env };
+    const excluded = ['node_options', 'node_path', 'npm_execpath', 'mcp_pacemaker_cli_context', 'path', 'psmodulepath',
+      'dotnet_startup_hooks', 'dotnet_additional_deps', 'dotnet_shared_store', 'complus_profapi_profilercompatibilitysetting'];
+    for (const key of Object.keys(env)) {
+      const lower = key.toLowerCase();
+      if (excluded.includes(lower) ||
+          /^(cor_|coreclr_|complus_|dotnet_)/.test(lower)) delete env[key];
+    }
+    env.PATH = dirname(this.powershell);
+    env.PSModulePath = join(dirname(this.powershell), 'Modules');
+    const output = this.run(this.powershell, ['-NoProfile', '-NonInteractive', '-File', script, '-Action', action], {
+      input: JSON.stringify({ ...input, taskPath: this.taskPath, targetSid: this.targetSid }),
+      cwd: dirname(this.powershell), env, encoding: 'utf8', windowsHide: true,
+      timeout: 20000, maxBuffer: 65536,
+    });
+    return JSON.parse(output);
+  }
+
+  inspect() { return this.call('inspect'); }
+  session(expected, port, root, managed) { return this.call('session', { expected, port, root, managed }); }
+  bootstrap(expected, original, bootstrap) { return this.call('bootstrap', { expected, original, bootstrap }); }
+  hold(expected, original) { return this.call('hold', { expected, original }); }
+  repoint(expected, original, launcher) { return this.call('repoint', { expected, original, launcher }); }
+  release(expected, original) { return this.call('release', { expected, original }); }
+  restore(expected, original) { return this.call('restore', { expected, original }); }
+  launch(expected, sessionId) { return this.call('launch', { expected, sessionId }); }
+}

package/bin/account-upgrade-controller.mjs

@@ -0,0 +1,198 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { readFileSync, realpathSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { AccountTaskAdapter, windowsArgument } from './account-task-adapter.mjs';
+import { authorizeTaskActor } from './task-scope.mjs';
+import { accountOperationReference, accountRecoveryTerminalPhases, ControllerSignatures, operationDigest, taskRevision, canonicalJson } from './task-transaction-protocol.mjs';
+import { TaskOnlyController, workerTaskRecord } from './task-only-controller.mjs';
+import { readInstanceState, readManagedJson, readRecoveryContext } from './managed-state.mjs';
+import { parseLegacyRegistration, verifyLegacyPackage, LEGACY_WARNING } from './legacy-installation.mjs';
+import { exactVersion } from './upgrade-package.mjs';
+import { canonicalPort } from './cli-selection.mjs';
+import { validateRegistry } from './update-check.mjs';
+
+const hash = path => createHash('sha256').update(readFileSync(path)).digest('hex');
+
+export function accountUpgradeOptions(args) {
+  const result = {};
+  let command = false;
+  for (let index = 0; index < args.length; index++) {
+    const value = args[index];
+    if (value === 'upgrade' && !command) { command = true; continue; }
+    if (['--plan', '--recover', '--yes'].includes(value)) {
+      if (result[value.slice(2)]) throw new Error('Repeated account operation flag.');
+      result[value.slice(2)] = true;
+      continue;
+    }
+    const key = ['--to', '--registry', '--instance', '--controller-root'].find(option => value === option || value.startsWith(`${option}=`));
+    if (key) {
+      const argument = value === key ? args[++index] : value.slice(key.length + 1);
+      if (!argument || argument.startsWith('-') || result[key.slice(2)]) throw new Error('Invalid account operation option.');
+      result[key.slice(2)] = argument;
+      continue;
+    }
+    throw new Error(`Unsupported account-management option: ${value}`);
+  }
+  if (!command || (result.recover ? Boolean(result.to) : !result.to)) throw new Error('Select an exact --to version or --recover.');
+  if (result.recover &&
+      (result.plan || result.registry !== undefined)) throw new Error('Explicit account recovery cannot combine --plan or --registry; it uses the recorded operation.');
+  if (result.to) exactVersion(result.to);
+  if (result.registry) result.registry = validateRegistry(result.registry);
+  if (result.yes && !result.plan) throw new Error('Original-account task bootstrap and restart require interactive confirmation; --yes cannot attest paused callers.');
+  return result;
+}
+
+export async function runAccountController(root, scope, {
+  channelApi, task, confirm, report = console.log, powershell,
+} = {}) {
+  if (process.platform !== 'win32') throw new Error('Explicit account management is Windows-only; --all-users is unsupported.');
+  const options = accountUpgradeOptions(scope.args);
+  if (options.instance !== undefined &&
+      options.instance !== scope.instance) throw new Error('Account instance selector disagrees with the parsed scope.');
+  if (options.recover &&
+      !scope.instance) throw new Error('Explicit account recovery requires --instance, not --task.');
+  const api = channelApi ?? await import('./windows-task-channel.mjs');
+  const { actorFacts: actor } = await api.queryTaskChannelCaller();
+  authorizeTaskActor(actor, scope.targetSid);
+  if (actor.elevated || actor.ownerSid !== scope.targetSid) await api.inspectTrustedCodeRoot(root);
+  const ps = powershell ?? join(process.env.ProgramFiles, 'PowerShell', '7', 'pwsh.exe');
+  if (!task && (actor.elevated || actor.ownerSid !== scope.targetSid)) await api.inspectTrustedCodeRoot(dirname(ps));
+  let selected;
+  let taskPath = scope.taskPath;
+  if (scope.instance) {
+    selected = readInstanceState(resolve(scope.instance));
+    if (options.recover && selected.controllerOperation?.targetSid === scope.targetSid) {
+      taskPath = selected.controllerOperation.taskPath;
+    } else {
+      const records = selected.autostart?.records;
+      if (selected.autostart?.kind !== 'stable' ||
+          records?.length !== 1 ||
+          typeof records[0].name !== 'string') throw new Error('Explicit account management requires one verified existing per-user registration.');
+      taskPath = `\\${records[0].name}`;
+    }
+  }
+  const adapter = task ?? new AccountTaskAdapter({ taskPath, targetSid: scope.targetSid, powershell: ps });
+  const context = await adapter.inspect();
+  const actual = context.record;
+  if (actual.path !== taskPath ||
+      actual.userSid !== scope.targetSid ||
+      actual.logonType !== 3 ||
+      actual.runLevel !== 0 ||
+      !actual.enabled ||
+      context.allowDemandStart !== true) throw new Error('The exact original interactive account cannot demand-start this registration.');
+  if (Buffer.byteLength(canonicalJson(actual)) > 8192) throw new Error('Task record exceeds the bounded account-channel contract.');
+  const home = selected ? dirname(selected.config) : join(realpathSync.native(context.profilePath), '.mcp-pacemaker');
+  let sourceRoot;
+  let port;
+  let from;
+  let original = actual;
+  let prior;
+  if (options.recover) {
+    if (!selected?.controllerOperation?.manifestPath) throw new Error('Recovery requires --instance with a recorded protected controller operation.');
+    const manifestPath = selected.controllerOperation.manifestPath;
+    await api.inspectTrustedCodeRoot(dirname(manifestPath));
+    const manifest = readManagedJson(manifestPath);
+    prior = readManagedJson(join(dirname(manifestPath), 'controller-journal.json'));
+    if (canonicalJson(selected.controllerOperation) !== canonicalJson(accountOperationReference(prior.binding)) ||
+        canonicalJson(manifest.document?.binding) !== canonicalJson(prior.binding) ||
+        manifest.document.digest !== operationDigest(prior.binding) ||
+        prior.binding.operationId !== manifest.operationId ||
+        manifest.targetSid !== scope.targetSid ||
+        manifest.sessionId !== prior.binding.sessionId ||
+        prior.binding.targetSid !== scope.targetSid ||
+        prior.binding.destination !== selected.directory ||
+        prior.binding.config !== selected.config ||
+        prior.binding.port !== selected.port ||
+        prior.binding.taskPath !== taskPath ||
+        taskRevision(prior.current) !== taskRevision(actual)) throw new Error('Protected controller recovery state disagrees with the selected task.');
+    if (manifest.document.initialTask &&
+        (taskRevision(manifest.document.initialTask) !== prior.binding.initialTaskRevision ||
+          taskRevision(prior.initial) !== prior.binding.initialTaskRevision)) {
+      throw new Error('Protected pre-bootstrap task revision disagrees with its operation binding.');
+    }
+    original = prior.original;
+    sourceRoot = prior.binding.root;
+    port = prior.binding.port;
+    from = prior.binding.from;
+    const recovery = readRecoveryContext(selected.directory);
+    if (accountRecoveryTerminalPhases.includes(recovery.journal.phase)) {
+      if (!['completed', 'failed-restored', 'restored'].includes(prior.phase)) {
+        throw new Error('Runtime journal is terminal but task outcome is unresolved; no bootstrap or automatic task rewrite was attempted.');
+      }
+      report('This runtime and controller transaction is already settled; no task or runtime change was made.');
+      return { status: recovery.journal.phase, directory: selected.directory, port: selected.port };
+    }
+  } else if (selected) {
+    sourceRoot = selected.active.root;
+    port = selected.port;
+    from = selected.active.version;
+    if (actual.actions.length !== 1 ||
+        actual.actions[0].arguments !== `"${join(selected.directory, 'launcher.vbs')}"`) throw new Error('The selected task is not bound to the managed launcher.');
+  } else {
+    const state = readManagedJson(join(home, 'state.json'));
+    const ports = [...new Set((state.hosts ?? []).map(host => canonicalPort(host.port)))];
+    if (ports.length !== 1) throw new Error('Account migration requires exactly one existing legacy port.');
+    port = ports[0];
+    sourceRoot = parseLegacyRegistration([workerTaskRecord(actual, scope.targetSid)], port).root;
+    verifyLegacyPackage(sourceRoot);
+    from = '1.3.0';
+  }
+  const session = options.recover
+    ? { sessionId: prior.binding.sessionId, supervisorImage: prior.binding.legacySupervisorImage }
+    : await adapter.session(actual, port, sourceRoot, selected ? { config: selected.config, cwd: selected.cwd } : undefined);
+  if (!Number.isInteger(session.sessionId) || session.sessionId <= 0) throw new Error('No verified original interactive session is available.');
+  const operationId = randomUUID();
+  const destination = selected?.directory ?? join(home, 'managed', `legacy-${port}-${operationId}`);
+  const parent = realpathSync.native(options['controller-root'] ?? process.env.LOCALAPPDATA ?? homedir());
+  const manifestPath = join(parent, operationId, 'manifest.json');
+  const scriptPath = fileURLToPath(new URL('./account-upgrade-worker.mjs', import.meta.url));
+  const nodePath = realpathSync.native(process.execPath);
+  const workerArgs = [scriptPath, '--manifest', manifestPath, '--operation', operationId, '--controller-root', parent];
+  const binding = {
+    protocol: 1, operationId, manifestPath, taskPath, targetSid: scope.targetSid, sessionId: session.sessionId,
+    kind: prior?.binding.kind ?? (selected ? 'managed' : 'legacy'), recover: Boolean(options.recover),
+    root: sourceRoot, home, config: selected?.config ?? join(home, 'servers.json'), port,
+    from, to: options.to ?? prior.binding.to, registry: options.registry ?? prior?.binding.registry ?? null,
+    destination, launcher: join(destination, 'launcher.vbs'),
+    originalTaskRevision: taskRevision(original), initialTaskRevision: taskRevision(actual),
+    legacySupervisorImage: session.supervisorImage ?? null,
+    previousControllerOperation: selected?.controllerOperation ?? null,
+    processQueryImage: { path: ps, sha256: hash(ps) },
+    bootstrapTask: { nodePath, arguments: workerArgs.map(windowsArgument).join(' '), cwd: root },
+  };
+  report(`Account scope: ${actor.ownerSid === scope.targetSid ? 'current user' : 'explicit other user'}; per-user installation only.\nTask: ${taskPath}\nPort: ${port}\nOriginal account/session preserved. No all-users conversion.\n${binding.kind === 'legacy' ? LEGACY_WARNING : 'Managed admission and job lifetime proof remain required.'}`);
+  if (options.plan) {
+    report('Read-only plan. Native logged-on session eligibility is checked at execution before bootstrap. Original-user dependency policy, staging and executable preflight will be verified before stop. No task was changed.');
+    return { status: 'planned', targetSid: scope.targetSid, taskPath, port };
+  }
+  if (!confirm) throw new Error('Interactive bootstrap confirmation is required.');
+  if (await confirm('Temporarily hold automatic starts and launch the trusted preparation worker under this exact original account? The current backend is not stopped by bootstrap.') !== true) {
+    return { status: 'cancelled' };
+  }
+  const signatures = new ControllerSignatures();
+  const channel = await api.createTaskChannel({
+    operationId, targetSid: scope.targetSid, sessionId: session.sessionId,
+    bootstrap: { nodePath, scriptPath, nodeSha256: hash(nodePath), scriptSha256: hash(scriptPath), argv: workerArgs },
+    manifestParent: parent,
+    manifest: {
+      binding, digest: operationDigest(binding), publicKey: signatures.publicKey,
+      initialTask: actual,
+      authorizedTaskRevisions: [
+        taskRevision(workerTaskRecord(original, scope.targetSid)),
+        taskRevision(workerTaskRecord(actual, scope.targetSid)),
+      ],
+    },
+  });
+  if (channel.manifestPath !== manifestPath) {
+    await channel.close();
+    throw new Error('Protected operation path differs from the sealed bootstrap.');
+  }
+  const controller = new TaskOnlyController({
+    binding, original, initial: actual, task: adapter, channel, signatures, confirm,
+    journalPath: join(dirname(manifestPath), 'controller-journal.json'),
+  });
+  report(`Recovery evidence: ${dirname(manifestPath)}`);
+  return controller.run();
+}

package/bin/account-upgrade-worker.mjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+import { fileURLToPath } from 'node:url';
+import { createHash } from 'node:crypto';
+import { resolve } from 'node:path';
+import { AccountWorkerSession } from './account-worker-session.mjs';
+import { readProtectedManifest } from './windows-task-channel.mjs';
+import { confirmLegacyUpgrade, legacyPlanDigest } from './legacy-installation.mjs';
+import { ManagedUpgrader, describeUpgrade, planUpgrade } from './managed-upgrade.mjs';
+import { readRecoveryContext } from './managed-state.mjs';
+import { accountOperationReference, accountRecoveryTerminalPhases, operationDigest, taskRevision, verifyTargetSession } from './task-transaction-protocol.mjs';
+
+export async function executeAccountUpgrade(session) {
+  const binding = session.binding;
+  process.chdir(binding.home);
+  const native = await import('./windows-legacy-process.mjs');
+  const processes = {
+    ...native,
+    prepareLegacyProcesses: async options => {
+      const held = await native.prepareLegacyProcesses(options);
+      try { session.verifyProcessSessions(held.plan); }
+      catch (error) { await held.close(); throw error; }
+      return {
+        ...held,
+        stop: async () => {
+          await session.call('INSPECT');
+          session.verifyProcessSessions(held.plan);
+          return held.stop();
+        },
+      };
+    },
+  };
+  const upgrader = new ManagedUpgrader({
+    legacy: { task: session, processes },
+    autostart: instance => session.inspectAutostart(instance),
+    beforeInterruption: async () => {
+      await session.hold(binding.port, session.logical);
+    },
+    beforeStop: async () => {
+      await session.call('INSPECT');
+      session.verifyManagedProcessSession();
+    },
+    beforeAdmission: async (instance, journal) => {
+      if (journal.rollback) {
+        await session.restore(binding.port, session.logical, session.original);
+        return;
+      }
+      const current = await session.repoint(binding.port, session.logical, binding.launcher);
+      await session.enable(binding.port, current);
+    },
+  });
+  if (binding.recover) {
+    const { instance, journal } = readRecoveryContext(binding.destination);
+    if (instance.config !== binding.config ||
+        instance.port !== binding.port ||
+        (journal.legacy && journal.legacy.root !== binding.root)) throw new Error('Recovery is outside the protected account scope.');
+    if (accountRecoveryTerminalPhases.includes(journal.phase)) {
+      throw new Error('Runtime recovery became terminal before worker approval; retry the read-only controller check.');
+    }
+    const approved = await session.call('PLAN', {
+      digest: operationDigest({ instance: instance.id, phase: journal.phase, target: {
+        root: journal.target.root, version: journal.target.version, directoryIdentity: journal.target.directoryIdentity,
+        inventorySha256: createHash('sha256').update(JSON.stringify(journal.target.files)).digest('hex'),
+      } }),
+      summary: 'Recover only this original-account instance. Uncertain task/traffic outcomes remain a refusal; no calls are replayed.',
+    });
+    if (!approved.approved) return { status: 'cancelled', directory: binding.destination, port: binding.port };
+    await session.hold(binding.port, session.logical);
+    const result = await upgrader.recover(binding.destination);
+    if (accountRecoveryTerminalPhases.includes(result.status) &&
+        result.status !== 'committed' &&
+        taskRevision(session.logical) !== taskRevision(session.original)) {
+      await session.restore(binding.port, session.logical, session.original);
+    }
+    return result;
+  }
+  const options = { to: binding.to, registry: binding.registry ?? undefined,
+    ...(binding.kind === 'managed' ? { instance: binding.destination } : {}) };
+  const plan = await planUpgrade(options, {
+    home: binding.home, legacy: { task: session, processes },
+    autostart: instance => session.inspectAutostart(instance),
+  });
+  if (plan.instance.config !== binding.config ||
+      plan.instance.port !== binding.port ||
+      (plan.legacy && plan.legacy.root !== binding.root)) throw new Error('Original-account discovery disagrees with the approved installation.');
+  plan.instance.directory = binding.destination;
+  if (plan.legacy) {
+    plan.instance.controllerOperation = accountOperationReference(binding);
+    const accepted = await confirmLegacyUpgrade(plan, {
+      interactive: true,
+      confirm: async message => {
+        const result = await session.call('PLAN', { digest: legacyPlanDigest(plan), summary: message });
+        return result.approved === true && result.digest === legacyPlanDigest(plan);
+      },
+    });
+    if (!accepted) return { status: 'cancelled', directory: binding.destination, port: binding.port };
+  } else {
+    const result = await session.call('PLAN', {
+      digest: operationDigest({ instance: plan.instance.id, to: plan.to, port: plan.port }),
+      summary: describeUpgrade(plan),
+    });
+    if (!result.approved) return { status: 'cancelled', directory: binding.destination, port: binding.port };
+  }
+  return upgrader.execute(plan);
+}
+
+export async function runAccountWorker(args = process.argv.slice(2), { execute = executeAccountUpgrade } = {}) {
+  if (args.length !== 6 ||
+      args[0] !== '--manifest' ||
+      args[2] !== '--operation' ||
+      args[4] !== '--controller-root') throw new Error('Invalid original-account bootstrap arguments.');
+  const protectedInput = await readProtectedManifest(args[1], { operationId: args[3], manifestParent: args[5] });
+  if (protectedInput.document.document.binding.manifestPath !== args[1]) throw new Error('Worker manifest path does not match the protected scope.');
+  verifyTargetSession(protectedInput.targetSession, protectedInput.document.targetSession);
+  const session = await new AccountWorkerSession(protectedInput.document, protectedInput.readerIdentity).open();
+  try {
+    const result = await execute(session);
+    if (result.status === 'cancelled') return result;
+    await session.call('DONE', {
+      status: result.status, directory: result.directory, port: result.port,
+      version: result.version ?? session.binding.from,
+    });
+    return result;
+  } catch (error) {
+    if (!session.failure) {
+      await session.call('FAILED', { message: 'The original-account operation did not complete; retain both journals.' }).catch(() => {});
+    }
+    throw error;
+  } finally { session.close(); }
+}
+
+if (process.argv[1] &&
+    resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  runAccountWorker().catch(error => { console.error(error.message); process.exitCode = 1; });
+}

package/bin/account-worker-session.mjs

@@ -0,0 +1,215 @@
+import { connect } from 'node:net';
+import { createHash } from 'node:crypto';
+import { execFileSync, spawn } from 'node:child_process';
+import { closeSync, openSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { accountOperationReference, operationDigest, taskRevision, WorkerSignatures } from './task-transaction-protocol.mjs';
+import { minimalTaskRecord } from './task-only-controller.mjs';
+import { durableJson, readManagedJson } from './managed-state.mjs';
+import { fileURLToPath } from 'node:url';
+
+export class AccountWorkerSession {
+  constructor(publicManifest, identity) {
+    this.manifest = publicManifest;
+    this.binding = publicManifest.document.binding;
+    if (this.binding.operationId !== publicManifest.operationId ||
+        this.binding.targetSid !== identity.ownerSid ||
+        this.binding.sessionId !== identity.sessionId ||
+        publicManifest.targetSid !== identity.ownerSid ||
+        publicManifest.sessionId !== identity.sessionId ||
+        operationDigest(this.binding) !== publicManifest.document.digest) throw new Error('Protected operation scope does not match the actual worker.');
+    this.signatures = new WorkerSignatures({
+      publicKey: publicManifest.document.publicKey, operationId: publicManifest.operationId,
+      digest: publicManifest.document.digest, identity, targetSession: publicManifest.targetSession,
+    });
+    this.queue = [];
+    this.waiters = [];
+    this.holdKind = 'automatic-triggers';
+    this.destination = this.binding.destination;
+    this.allowed = new Set(publicManifest.document.authorizedTaskRevisions ?? []);
+  }
+
+  async open() {
+    this.socket = connect(this.manifest.endpoint);
+    this.socket.setEncoding('utf8');
+    let pending = '';
+    const fail = error => {
+      this.failure = error;
+      for (const waiter of this.waiters.splice(0)) waiter.reject(error);
+    };
+    this.socket.on('error', fail);
+    this.socket.on('close', () => fail(new Error('Controller channel closed; no reconnect or privileged fallback.')));
+    this.socket.on('data', chunk => {
+      pending += chunk;
+      if (Buffer.byteLength(pending) > 16384) { this.socket.destroy(new Error('Oversized controller response.')); return; }
+      const newline = pending.indexOf('\n');
+      if (newline < 0) return;
+      const text = pending.slice(0, newline);
+      pending = pending.slice(newline + 1);
+      try {
+        const response = JSON.parse(text);
+        const waiter = this.waiters.shift();
+        if (waiter) waiter.resolve(response);
+        else this.queue.push(response);
+        if (this.queue.length > 1 || pending.length) this.socket.destroy(new Error('Unsolicited controller frames.'));
+      } catch (error) { this.socket.destroy(error); }
+    });
+    await new Promise((resolveConnected, reject) => {
+      this.socket.once('connect', resolveConnected);
+      this.socket.once('error', reject);
+    });
+    const hello = await this.call('HELLO', { challenge: this.signatures.challenge, identity: this.signatures.identity });
+    this.original = hello.original;
+    this.logical = this.original;
+    this.allowed.add(taskRevision(this.original));
+    return this;
+  }
+
+  async call(verb, body = null) {
+    if (this.failure) throw this.failure;
+    if (this.busy) throw new Error('Only one original-account task request may be outstanding.');
+    this.busy = true;
+    let timer;
+    try {
+      const request = this.signatures.request(verb, body);
+      const response = new Promise((resolveResponse, reject) => {
+        timer = setTimeout(() => reject(new Error('Controller response timed out; task outcome is uncertain.')), verb === 'PLAN' ? 300000 : 30000);
+        if (this.queue.length) resolveResponse(this.queue.shift());
+        else this.waiters.push({ resolve: resolveResponse, reject });
+      });
+      this.socket.write(`${JSON.stringify(request)}\n`);
+      return this.signatures.accept(await response, request);
+    } catch (error) {
+      this.failure = error;
+      this.socket.destroy();
+      throw error;
+    } finally { clearTimeout(timer); this.busy = false; }
+  }
+
+  async inspectLegacySource() {
+    await this.call('INSPECT');
+    return [this.original];
+  }
+
+  async verifyBinding(instance, expected) {
+    if (instance.port !== this.binding.port ||
+        instance.config !== this.binding.config ||
+        !this.allowed.has(taskRevision(expected))) throw new Error('Worker task binding is outside the protected operation.');
+    await this.call('INSPECT');
+    return expected;
+  }
+
+  async taskCall(verb, expected) {
+    if (!this.allowed.has(taskRevision(expected))) throw new Error('Unknown worker task revision.');
+    const result = await this.call(verb);
+    this.logical = result.record;
+    this.allowed.add(taskRevision(result.record));
+    return result.record;
+  }
+
+  async hold(port, expected) {
+    if (port !== this.binding.port) throw new Error('Task hold is outside the original account port.');
+    const path = join(this.binding.destination, 'instance.json');
+    const instance = readManagedJson(path);
+    if (instance.config !== this.binding.config ||
+        instance.port !== port) throw new Error('Worker instance differs from its protected operation.');
+    const reference = accountOperationReference(this.binding);
+    if (!isDeepStrictEqual(instance.controllerOperation, reference)) {
+      if ((this.binding.kind === 'legacy' && !this.binding.recover) ||
+          !isDeepStrictEqual(instance.controllerOperation ?? null, this.binding.previousControllerOperation ?? null)) {
+        throw new Error('Published controller operation is missing or changed; no task hold was requested.');
+      }
+      durableJson(path, { ...instance, controllerOperation: reference });
+    }
+    return this.taskCall('HOLD', expected);
+  }
+  repoint(port, expected, launcher) {
+    if (launcher !== this.binding.launcher) throw new Error('Worker cannot choose the elevated task launcher.');
+    return this.taskCall('REPOINT', expected);
+  }
+  enable(port, expected) { return this.taskCall('ENABLE', expected); }
+  restore(port, expected, original) {
+    if (taskRevision(original) !== taskRevision(this.original)) throw new Error('Worker cannot supply a replacement task definition.');
+    return this.taskCall('RESTORE', expected);
+  }
+  async stableRecords() { return (await this.call('RECORDS')).records; }
+
+  async start(port, expected) {
+    if (port !== this.binding.port ||
+        taskRevision(expected) !== taskRevision(this.original)) throw new Error('Rollback is outside the original-account binding.');
+    const image = this.binding.legacySupervisorImage;
+    if (!image ||
+        createHash('sha256').update(readFileSync(image.path)).digest('hex') !== image.sha256) throw new Error('Original supervisor image changed before rollback.');
+    const log = openSync(join(this.binding.destination, 'rollback-launcher.log'), 'a', 0o600);
+    let child;
+    try {
+      child = spawn(image.path, [
+        '-NoProfile', '-ExecutionPolicy', 'Bypass', '-WindowStyle', 'Hidden',
+        '-File', join(this.binding.root, 'supervisor', 'supervise.ps1'), '-Port', String(port),
+      ], { cwd: dirname(this.binding.config), env: { ...process.env }, windowsHide: true,
+        stdio: ['ignore', log, log] });
+    } finally { closeSync(log); }
+    await new Promise((resolveStart, reject) => {
+      child.once('spawn', resolveStart);
+      child.once('error', reject);
+    });
+    child.once('exit', (code, signal) => {
+      durableJson(join(this.binding.destination, 'rollback-launch-exit.json'), { pid: child.pid, code, signal, imagePath: image.path });
+    });
+    child.unref();
+  }
+
+  verifyProcessSessions(plan) {
+    if (plan.ownerSid !== this.binding.targetSid ||
+        plan.root !== this.binding.root ||
+        plan.port !== this.binding.port) throw new Error('Legacy process scope differs from the protected operation.');
+    const identities = [plan.roots.supervisor, plan.roots.bridge, ...plan.observed]
+      .map(({ pid, creationTime, ownerSid }) => ({ pid, creationTime, ownerSid }));
+    if (identities.length < 2 ||
+        identities.length > 512 ||
+        new Set(identities.map(identity => identity.pid)).size !== identities.length) {
+      throw new Error('Unsupported captured identity count or duplicate process.');
+    }
+    for (const identity of identities) {
+      if (!Number.isInteger(identity.pid) ||
+          identity.pid <= 0 ||
+          identity.pid > 2147483647 ||
+          identity.ownerSid !== this.binding.targetSid ||
+          typeof identity.creationTime !== 'string' ||
+          !/^[1-9][0-9]{0,18}$/.test(identity.creationTime)) {
+        throw new Error('Invalid captured original-user identity.');
+      }
+    }
+    this.queryProcessSessions({ identities });
+  }
+
+  verifyManagedProcessSession() {
+    this.queryProcessSessions({ port: this.binding.port });
+  }
+
+  queryProcessSessions(selection) {
+    const image = this.binding.processQueryImage;
+    if (!image ||
+        createHash('sha256').update(readFileSync(image.path)).digest('hex') !== image.sha256) throw new Error('Original-user query host changed.');
+    const input = JSON.stringify({ ownerSid: this.binding.targetSid, sessionId: this.binding.sessionId, ...selection });
+    if (Buffer.byteLength(input, 'utf8') > 131072) throw new Error('Worker identity request exceeds its bound.');
+    const output = execFileSync(image.path, ['-NoProfile', '-NonInteractive', '-File',
+      fileURLToPath(new URL('../autostart/windows/inspect-worker-process-sessions.ps1', import.meta.url)),
+    ], {
+      input,
+      encoding: 'utf8', windowsHide: true, timeout: 15000, maxBuffer: 16384,
+    });
+    if (JSON.parse(output).verified !== true) throw new Error('Original-user process session inspection did not verify.');
+  }
+
+  async inspectAutostart(instance) {
+    if (instance.directory !== this.binding.destination ||
+        instance.autostart.kind !== 'stable' ||
+        !isDeepStrictEqual(instance.autostart.records, [minimalTaskRecord(this.original)])) throw new Error('Managed autostart does not match the selected original registration.');
+    await this.call('INSPECT');
+    return { kind: 'stable', launcher: this.binding.launcher };
+  }
+
+  close() { this.socket?.end(); }
+}