mcp-pacemaker 2.0.1 → 2.1.0

package/autostart/windows/account-task.ps1

@@ -0,0 +1,167 @@
+<#
+.SYNOPSIS
+Performs fixed controller task operations while preserving the registered account.
+.DESCRIPTION
+Reads a bounded controller request on stdin. This adapter changes only the exact
+selected registration, preserving principal, logon type, run level and full security.
+It never stops processes, edits configuration, enables privileges or changes ACLs.
+.PARAMETER Action
+Exact task operation chosen by the trusted controller.
+.OUTPUTS
+Bounded JSON task/profile/session evidence. A successful launch call is not readiness.
+.EXAMPLE
+.\account-task.ps1 -Action inspect
+#>
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory)]
+    [ValidateSet('inspect', 'session', 'bootstrap', 'hold', 'repoint', 'release', 'restore', 'launch')]
+    [string]$Action
+)
+$ErrorActionPreference = 'Stop'
+. (Join-Path $PSScriptRoot 'legacy-task.ps1') -Operation inspect -Port 1 -FunctionsOnly
+$text = [Console]::In.ReadToEnd()
+if ($text.Length -gt 65536) { throw 'Controller request exceeds its bound.' }
+$request = $text | ConvertFrom-Json
+$targetSid = $request.targetSid
+if ($targetSid -cnotmatch '^S-1-[0-9]+(?:-[0-9]+)+$' -or
+    ([Security.Principal.SecurityIdentifier]::new($targetSid)).Value -cne $targetSid) {
+    throw 'A canonical target SID is required.'
+}
+$impersonated = [Security.Principal.WindowsIdentity]::GetCurrent($true)
+if ($null -ne $impersonated) {
+    $impersonated.Dispose()
+    throw 'Impersonating task-adapter contexts are unsupported.'
+}
+$identity = [Security.Principal.WindowsIdentity]::GetCurrent()
+$principal = [Security.Principal.WindowsPrincipal]::new($identity)
+if ($targetSid -cne $currentSid -and
+    -not $principal.IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)) {
+    throw 'The current task-adapter token is not an enabled administrator.'
+}
+$path = $request.taskPath
+if ([string]::IsNullOrEmpty($path) -or
+    $path.Length -gt 1024 -or
+    -not $path.StartsWith('\') -or
+    $path.Contains('/') -or
+    $path.Split('\') -contains '..') { throw 'An exact task path is required.' }
+$separator = $path.LastIndexOf('\')
+$folderPath = if ($separator -eq 0) { '\' } else { $path.Substring(0, $separator) }
+$name = $path.Substring($separator + 1)
+$service = New-Object -ComObject Schedule.Service
+$service.Connect()
+$folder = $service.GetFolder($folderPath)
+$task = $folder.GetTask($name)
+$record = Get-TaskRecord -Task $task
+$record.runAsName = $task.Definition.Principal.UserId
+if ($record.path -cne $path -or
+    $record.userSid -cne $targetSid -or
+    $record.logonType -ne 3 -or
+    $record.runLevel -ne 0) { throw 'Selected task does not preserve the requested interactive account.' }
+Assert-TaskSecurity -Actual $record.security -Expected $record.security -RuntimeSid $targetSid
+if ($Action -eq 'inspect') {
+    $profiles = @(Get-CimInstance -ClassName Win32_UserProfile -Filter "SID='$targetSid'" -Property SID, LocalPath, Loaded -OperationTimeoutSec 10)
+    if ($profiles.Count -ne 1 -or
+        -not $profiles[0].Loaded) { throw 'The selected user profile is not loaded in an existing interactive session.' }
+    @{
+        record = $record
+        profilePath = [IO.Path]::GetFullPath($profiles[0].LocalPath)
+        allowDemandStart = $task.Definition.Settings.AllowDemandStart
+    } | ConvertTo-Json -Depth 12 -Compress
+    return
+}
+if ($record.xmlSha256 -cne $request.expected.xmlSha256 -or
+    $record.userSid -cne $request.expected.userSid) { throw 'Task definition changed after the approved plan.' }
+Assert-TaskSecurity -Actual $record.security -Expected $request.expected.security -RuntimeSid $targetSid
+if ($Action -eq 'session') {
+    $port = [int]$request.port
+    if ($port -lt 1 -or $port -gt 65535) { throw 'Invalid selected port.' }
+    $listeners = @(Get-CimInstance -Namespace 'root/StandardCimv2' -ClassName MSFT_NetTCPConnection `
+        -Filter "LocalAddress='127.0.0.1' AND LocalPort=$port AND State=2" -OperationTimeoutSec 10)
+    if ($listeners.Count -ne 1) { throw 'Selected listener is absent or ambiguous.' }
+    $processId = [int]$listeners[0].OwningProcess
+    $process = Get-CimInstance -ClassName Win32_Process -Filter "ProcessId=$processId" -Property ProcessId, ParentProcessId, SessionId, CreationDate, CommandLine, ExecutablePath -OperationTimeoutSec 10
+    $owner = Invoke-CimMethod -InputObject $process -MethodName GetOwnerSid -ErrorAction Stop
+    $scriptPath = [IO.Path]::GetFullPath((Join-Path $request.root 'bin\mcp-bridge.mjs'))
+    $commands = @(
+        "`"$($process.ExecutablePath)`" `"$scriptPath`" --port $port",
+        "$($process.ExecutablePath) `"$scriptPath`" --port $port"
+    )
+    if ($null -ne $request.managed) {
+        $parts = @((Join-Path $request.root 'supervisor\bridge-child.mjs'), '--port', "$port", '--config', $request.managed.config, '--cwd', $request.managed.cwd)
+        $arguments = ($parts | ForEach-Object {
+            if ($_ -match '\s') { "`"$_`"" } else { $_ }
+        }) -join ' '
+        $commands = @("`"$($process.ExecutablePath)`" $arguments", "$($process.ExecutablePath) $arguments")
+    }
+    if ($owner.ReturnValue -ne 0 -or
+        $owner.Sid -cne $targetSid -or
+        $process.SessionId -le 0 -or
+        $process.CommandLine -notin $commands) {
+        throw 'Selected listener account/session/absolute legacy command could not be verified.'
+    }
+    $parentId = [int]$process.ParentProcessId
+    $parent = Get-CimInstance -ClassName Win32_Process -Filter "ProcessId=$parentId" -Property ProcessId, ExecutablePath, SessionId, CreationDate -OperationTimeoutSec 10
+    $parentOwner = Invoke-CimMethod -InputObject $parent -MethodName GetOwnerSid -ErrorAction Stop
+    if ($parentOwner.ReturnValue -ne 0 -or
+        $parentOwner.Sid -cne $targetSid -or
+        $parent.SessionId -ne $process.SessionId -or
+        $parent.CreationDate -gt $process.CreationDate) { throw 'Selected supervisor account/session/generation is ambiguous.' }
+    @{ ownerSid = $owner.Sid; sessionId = $process.SessionId; pid = $processId
+        createdUtc = $process.CreationDate.ToUniversalTime().ToString('o')
+        supervisorImage = @{ path = $parent.ExecutablePath; sha256 = (Get-FileHash -LiteralPath $parent.ExecutablePath -Algorithm SHA256).Hash.ToLowerInvariant() }
+    } | ConvertTo-Json -Depth 4 -Compress
+    return
+}
+if ($Action -eq 'launch') {
+    if (-not $task.Enabled -or
+        -not $task.Definition.Settings.AllowDemandStart -or
+        $request.sessionId -le 0) { throw 'The selected task cannot demand-start in the requested session.' }
+    $running = $task.RunEx($null, 12, [int]$request.sessionId, $targetSid)
+    @{ requested = $true; instanceGuid = $running.InstanceGuid; readinessProven = $false } | ConvertTo-Json -Compress
+    return
+}
+$definition = $task.Definition
+switch ($Action) {
+    'bootstrap' {
+        if (-not $task.Enabled -or
+            -not $definition.Settings.AllowDemandStart) { throw 'Bootstrap requires an enabled demand-start task.' }
+        if ($definition.Actions.Count -ne 1) { throw 'Unsupported task actions.' }
+        $definition.Actions.Item(1).Path = $request.bootstrap.nodePath
+        $definition.Actions.Item(1).Arguments = $request.bootstrap.arguments
+        $definition.Actions.Item(1).WorkingDirectory = $request.bootstrap.cwd
+        foreach ($trigger in $definition.Triggers) { $trigger.Enabled = $false }
+        $definition.Settings.RestartCount = 0
+    }
+    'repoint' {
+        if ($definition.Actions.Count -ne 1) { throw 'Unsupported task actions.' }
+        $definition.Actions.Item(1).Path = 'wscript.exe'
+        $definition.Actions.Item(1).Arguments = "`"$($request.launcher)`""
+        $definition.Actions.Item(1).WorkingDirectory = ''
+    }
+    'hold' {
+        foreach ($trigger in $definition.Triggers) { $trigger.Enabled = $false }
+        $definition.Settings.RestartCount = 0
+    }
+    'release' {
+        $original = $service.NewTask(0)
+        $original.XmlText = $request.original.xml
+        if ($original.Triggers.Count -ne $definition.Triggers.Count) { throw 'Task trigger identity changed.' }
+        for ($index = 1; $index -le $definition.Triggers.Count; $index++) {
+            $definition.Triggers.Item($index).Enabled = $original.Triggers.Item($index).Enabled
+        }
+        $definition.Settings.RestartCount = $original.Settings.RestartCount
+    }
+    'restore' { $definition.XmlText = $request.original.xml }
+}
+Assert-TaskSecurity -Actual $record.security -Expected $request.original.security -RuntimeSid $targetSid
+if ((Get-UserSid -User $definition.Principal.UserId) -cne $targetSid -or
+    $definition.Principal.LogonType -ne $record.logonType -or
+    $definition.Principal.RunLevel -ne $record.runLevel) { throw 'Task account semantics changed.' }
+$expectedXml = $definition.XmlText
+$folder.RegisterTaskDefinition($name, $definition, 52, $definition.Principal.UserId, $null, 3, $record.security.sddl) | Out-Null
+$updated = Get-TaskRecord -Task ($folder.GetTask($name))
+$updated.runAsName = $definition.Principal.UserId
+Assert-TaskSecurity -Actual $updated.security -Expected $record.security -RuntimeSid $targetSid
+if ($updated.xmlSha256 -cne (Get-XmlHash -Xml $expectedXml)) { throw 'Task update outcome differs from the exact requested definition.' }
+$updated | ConvertTo-Json -Depth 12 -Compress

package/autostart/windows/inspect-task.ps1

@@ -0,0 +1,42 @@
+<#
+.SYNOPSIS
+Reads the selected per-user Pacemaker task and its legacy task identity.
+.DESCRIPTION
+Returns task actions and principal data without changing tasks or processes.
+.PARAMETER Port
+Selected service port.
+.OUTPUTS
+JSON array of existing task identities.
+.EXAMPLE
+.\inspect-task.ps1 -Port 8791
+#>
+[CmdletBinding()]
+param([ValidateRange(1, 65535)][int]$Port)
+
+$ErrorActionPreference = 'Stop'
+$service = New-Object -ComObject Schedule.Service
+$service.Connect()
+$folder = $service.GetFolder('\')
+$names = @("McpPacemaker-$Port", 'McpPacemaker')
+$records = @()
+foreach ($task in $folder.GetTasks(1)) {
+  if ($task.Name -notin $names) { continue }
+  $actions = @()
+  foreach ($action in $task.Definition.Actions) {
+    $actions += @{
+      type = $action.Type
+      path = $action.Path
+      arguments = $action.Arguments
+      workingDirectory = $action.WorkingDirectory
+    }
+  }
+  $records += @{
+    name = $task.Name
+    enabled = $task.Enabled
+    user = $task.Definition.Principal.UserId
+    logonType = $task.Definition.Principal.LogonType
+    runLevel = $task.Definition.Principal.RunLevel
+    actions = $actions
+  }
+}
+ConvertTo-Json -InputObject $records -Depth 5 -Compress

package/autostart/windows/inspect-worker-process-sessions.ps1

@@ -0,0 +1,155 @@
+<#
+.SYNOPSIS
+Checks session facts for the original-user broker's bounded captured identities.
+.DESCRIPTION
+Reads a same-user request on stdin. Queries only its listed process identities,
+or the selected managed loopback listener, and performs no process or security
+mutation. Native held-generation revalidation remains the stop authority.
+.OUTPUTS
+A verification result without command lines or account identifiers.
+.EXAMPLE
+.\inspect-worker-process-sessions.ps1
+#>
+[CmdletBinding()]
+param()
+$ErrorActionPreference = 'Stop'
+$watch = [Diagnostics.Stopwatch]::StartNew()
+$stream = [Console]::OpenStandardInput()
+$bytes = [byte[]]::new(131073)
+$length = 0
+while ($length -lt $bytes.Length) {
+    $read = $stream.Read($bytes, $length, $bytes.Length - $length)
+    if ($read -eq 0) { break }
+    $length += $read
+}
+if ($length -gt 131072) { throw 'Worker identity request exceeds its bound.' }
+$text = [Text.UTF8Encoding]::new($false, $true).GetString($bytes, 0, $length)
+$request = $text | ConvertFrom-Json
+$sid = [Security.Principal.WindowsIdentity]::GetCurrent().User.Value
+$hasSessionType = $request.sessionId -is [long] -or $request.sessionId -is [int]
+if ($request.ownerSid -isnot [string] -or
+    $request.ownerSid -cne $sid -or
+    $request.ownerSid.Length -gt 184 -or
+    -not $hasSessionType -or
+    $request.sessionId -ne [Diagnostics.Process]::GetCurrentProcess().SessionId) {
+    throw 'Worker process/session scope is not the actual current account.'
+}
+if ($null -ne $request.port) {
+    if ((($request.PSObject.Properties.Name | Sort-Object) -join ',') -cne 'ownerSid,port,sessionId') {
+        throw 'Invalid managed listener request shape.'
+    }
+    $port = [int]$request.port
+    if ($port -lt 1 -or
+        $port -gt 65535 -or
+        $null -ne $request.identities) { throw 'Invalid managed listener scope.' }
+    $listeners = @(Get-CimInstance -Namespace 'root/StandardCimv2' -ClassName MSFT_NetTCPConnection `
+        -Filter "LocalAddress='127.0.0.1' AND LocalPort=$port AND State=2" -OperationTimeoutSec 10)
+    # A verified stopped/failed-start generation has no listener; its native proof is checked by the caller.
+    if ($listeners.Count -eq 0) {
+        '{"verified":true}'
+        return
+    }
+    if ($listeners.Count -ne 1) { throw 'Managed listener is ambiguous.' }
+    $processId = [int]$listeners[0].OwningProcess
+    $row = Get-CimInstance -ClassName Win32_Process -Filter "ProcessId=$processId" -OperationTimeoutSec 10
+    $owner = Invoke-CimMethod -InputObject $row -MethodName GetOwnerSid -ErrorAction Stop
+    if ($null -eq $row -or
+        $row.SessionId -ne $request.sessionId -or
+        $owner.ReturnValue -ne 0 -or
+        $owner.Sid -cne $sid) { throw 'Managed listener account/session changed; replan before stop.' }
+    '{"verified":true}'
+    return
+}
+if ((($request.PSObject.Properties.Name | Sort-Object) -join ',') -cne 'identities,ownerSid,sessionId' -or
+    $request.identities -isnot [Array]) { throw 'Invalid captured identity request shape.' }
+$identities = @($request.identities)
+if ($identities.Count -lt 2 -or
+    $identities.Count -gt 512) { throw 'Captured identity count is unsupported.' }
+$seen = @{}
+foreach ($identity in $identities) {
+    if ((($identity.PSObject.Properties.Name | Sort-Object) -join ',') -cne 'creationTime,ownerSid,pid' -or
+        ($identity.pid -isnot [long] -and $identity.pid -isnot [int]) -or
+        $identity.pid -le 0 -or
+        $identity.pid -gt [int]::MaxValue -or
+        $identity.ownerSid -isnot [string] -or
+        $identity.creationTime -isnot [string]) { throw 'Invalid captured identity shape.' }
+    $number = [int]$identity.pid
+    if ($seen.ContainsKey($number) -or
+        $identity.ownerSid -cne $sid -or
+        $identity.creationTime -cnotmatch '^[1-9][0-9]{0,18}$') {
+        throw 'Invalid original-user captured identity.'
+    }
+    $null = [DateTime]::FromFileTimeUtc([long]$identity.creationTime)
+    $seen[$number] = $true
+}
+$query = {
+    param([string]$Filter)
+    $ErrorActionPreference = 'Stop'
+    Import-Module CimCmdlets -ErrorAction Stop
+    $session = New-CimSession -ErrorAction Stop
+    try {
+        foreach ($row in Get-CimInstance -CimSession $session -ClassName Win32_Process -Filter $Filter `
+            -Property ProcessId, SessionId, CreationDate -OperationTimeoutSec 2) {
+            [pscustomobject]@{
+                pid = [int]$row.ProcessId
+                sessionId = [int]$row.SessionId
+                creationTicks = $row.CreationDate.ToUniversalTime().Ticks
+            }
+        }
+    } finally { Remove-CimSession -CimSession $session }
+}
+$observed = @{}
+$pool = [RunspaceFactory]::CreateRunspacePool(1, 4)
+$pool.Open()
+try {
+    for ($offset = 0; $offset -lt $identities.Count; $offset += 128) {
+        $pending = @()
+        try {
+            for ($index = $offset; $index -lt [Math]::Min($offset + 128, $identities.Count); $index += 32) {
+                if ($watch.ElapsedMilliseconds -ge 13000) { throw 'Worker session query deadline.' }
+                $batch = @($identities[$index..([Math]::Min($index + 31, $identities.Count - 1))])
+                $expected = @{}
+                $clauses = foreach ($identity in $batch) {
+                    $expected[[int]$identity.pid] = $true
+                    'ProcessId=' + ([int]$identity.pid).ToString([Globalization.CultureInfo]::InvariantCulture)
+                }
+                $pipeline = [PowerShell]::Create()
+                $pipeline.RunspacePool = $pool
+                $null = $pipeline.AddScript($query.ToString()).AddArgument(($clauses -join ' OR '))
+                $pending += @{ Pipeline = $pipeline; Expected = $expected; Result = $pipeline.BeginInvoke() }
+            }
+            foreach ($item in $pending) {
+                while (-not $item.Result.IsCompleted) {
+                    if ($watch.ElapsedMilliseconds -ge 13000) { throw 'Worker session query deadline.' }
+                    Start-Sleep -Milliseconds 10
+                }
+                $rows = @($item.Pipeline.EndInvoke($item.Result))
+                if ($item.Pipeline.HadErrors -or
+                    $rows.Count -ne $item.Expected.Count) { throw 'Worker session query did not return its exact captured set.' }
+                foreach ($row in $rows) {
+                    $number = [int]$row.pid
+                    if (-not $item.Expected.ContainsKey($number) -or
+                        $observed.ContainsKey($number)) { throw 'Worker session query returned an unexpected or duplicate identity.' }
+                    $observed[$number] = $row
+                }
+            }
+        } finally {
+            foreach ($item in $pending) {
+                if (-not $item.Result.IsCompleted) { $item.Pipeline.Stop() }
+                $item.Pipeline.Dispose()
+            }
+        }
+    }
+} finally { $pool.Close(); $pool.Dispose() }
+foreach ($identity in $identities) {
+    $matching = $observed[[int]$identity.pid]
+    if ($null -eq $matching -or
+        $matching.sessionId -ne $request.sessionId) { throw 'Captured generation/session changed; replan before stop.' }
+    $actual = $matching.creationTicks
+    $expected = [DateTime]::FromFileTimeUtc([long]$identity.creationTime).Ticks
+    # CIM creation dates have microsecond precision; this read never authorizes termination.
+    if ([decimal]::Truncate([decimal]$actual / 10) -ne [decimal]::Truncate([decimal]$expected / 10)) {
+        throw 'Captured process birth changed; replan before stop.'
+    }
+}
+'{"verified":true}'

package/autostart/windows/legacy-task.ps1

@@ -0,0 +1,301 @@
+<#
+.SYNOPSIS
+Inspects or updates one identity-bound per-user Pacemaker registration.
+.DESCRIPTION
+Reads a bounded JSON request from standard input. Mutations require the exact
+task XML and full owner/group/DACL/SACL/integrity descriptor. Does not enable
+privileges, repair permissions or stop processes.
+.PARAMETER Operation
+The scoped task operation to perform.
+.PARAMETER Port
+The selected Pacemaker port.
+.PARAMETER FunctionsOnly
+Loads shared task inspection/security functions without connecting to Task Scheduler.
+.OUTPUTS
+JSON task identity including its XML for protected backup and scoped restoration.
+.EXAMPLE
+.\legacy-task.ps1 -Operation inspect -Port 8791
+#>
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory)]
+    [ValidateSet('inspect', 'hold', 'repoint', 'enable', 'restore', 'start', 'compare-restored')]
+    [string]$Operation,
+    [Parameter(Mandatory)]
+    [ValidateRange(1, 65535)]
+    [int]$Port,
+    [switch]$FunctionsOnly
+)
+
+$ErrorActionPreference = 'Stop'
+$currentSid = [Security.Principal.WindowsIdentity]::GetCurrent().User.Value
+$ownerPolicy = (Get-Content -Raw -LiteralPath (Join-Path $PSScriptRoot '..\..\bin\legacy-1.3.json') | ConvertFrom-Json).taskOwnerPolicy
+if ($ownerPolicy.protocol -ne 1 -or
+    $ownerPolicy.allowRuntimeUser -ne $true -or
+    $null -eq $ownerPolicy.allowedOwnerSids) { throw 'Unsupported task owner policy.' }
+
+function Get-UserSid {
+    param([string]$User)
+    if ($User.StartsWith('S-1-', [StringComparison]::Ordinal)) { return $User }
+    $account = [Security.Principal.NTAccount]::new($User)
+    return $account.Translate([Security.Principal.SecurityIdentifier]).Value
+}
+
+function Get-XmlHash {
+    param([string]$Xml)
+    $algorithm = [Security.Cryptography.SHA256]::Create()
+    try {
+        return [Convert]::ToHexString($algorithm.ComputeHash([Text.Encoding]::UTF8.GetBytes($Xml))).ToLowerInvariant()
+    }
+    finally { $algorithm.Dispose() }
+}
+
+function ConvertTo-TaskSecurity {
+    param([string]$Sddl)
+    try {
+        if ([string]::IsNullOrEmpty($Sddl) -or
+            $Sddl.Length -gt 65536) { throw 'Unsupported descriptor length.' }
+        $descriptor = [Security.AccessControl.RawSecurityDescriptor]::new($Sddl)
+        if ($null -eq $descriptor.Owner -or
+            $null -eq $descriptor.Group) { throw 'Missing resource owner/group.' }
+        return @{
+            protocol = 1
+            information = 31
+            complete = $true
+            ownerSid = $descriptor.Owner.Value
+            groupSid = $descriptor.Group.Value
+            controlFlags = [int]$descriptor.ControlFlags
+            # AccessControlSections.All omits the LABEL flag when reserializing SDDL.
+            sddl = $Sddl
+            sha256 = Get-XmlHash -Xml $Sddl
+        }
+    }
+    catch { throw 'TASK_SECURITY_UNVERIFIED: Full task security descriptor could not be represented. No security fallback is allowed.' }
+}
+
+function Get-TaskSecurity {
+    param($Task)
+    try {
+        # OWNER | GROUP | DACL | SACL | LABEL; omitted audit data is not an empty SACL.
+        $sddl = $Task.GetSecurityDescriptor(31)
+    }
+    catch {
+        throw 'TASK_SECURITY_UNVERIFIED: Owner/group/DACL/SACL/integrity inspection was denied or unsupported. Further operations are refused; this adapter does not enable security privilege or elevate.'
+    }
+    return ConvertTo-TaskSecurity -Sddl $sddl
+}
+
+function Assert-TaskSecurity {
+    param($Actual, $Expected, [string]$RuntimeSid = $currentSid)
+    $recorded = ConvertTo-TaskSecurity -Sddl $Expected.sddl
+    if ($Expected.protocol -ne 1 -or
+        $Expected.information -ne 31 -or
+        $Expected.complete -ne $true -or
+        $Expected.sha256 -cne $recorded.sha256 -or
+        $Expected.ownerSid -cne $recorded.ownerSid -or
+        $Expected.groupSid -cne $recorded.groupSid -or
+        $Expected.controlFlags -ne $recorded.controlFlags -or
+        $Actual.sha256 -cne $recorded.sha256 -or
+        -not ($Actual.ownerSid -ceq $RuntimeSid -or
+              $Actual.ownerSid -cin $ownerPolicy.allowedOwnerSids)) {
+        throw 'TASK_SECURITY_CHANGED: Resource owner, permissions, audit or integrity no longer matches the approved task. Further operations are refused.'
+    }
+}
+
+function Get-TaskRecord {
+    param($Task)
+    $definition = $Task.Definition
+    $actions = @($definition.Actions | ForEach-Object {
+        @{
+            type = $_.Type
+            path = $_.Path
+            arguments = $_.Arguments
+            workingDirectory = [string]$_.WorkingDirectory
+        }
+    })
+    $triggers = @($definition.Triggers | ForEach-Object {
+        @{
+            type = $_.Type
+            userSid = Get-UserSid -User $_.UserId
+            enabled = $_.Enabled
+            stateChange = if ($_.Type -eq 11) { $_.StateChange } else { 0 }
+        }
+    })
+    $xml = $Task.Xml
+    if ($xml.Length -gt 524288) { throw 'Selected task XML exceeds the supported bound.' }
+    return @{
+        name = $Task.Name
+        path = $Task.Path
+        enabled = $Task.Enabled
+        xml = $xml
+        xmlSha256 = Get-XmlHash -Xml $xml
+        security = Get-TaskSecurity -Task $Task
+        currentUserSid = $currentSid
+        userSid = Get-UserSid -User $definition.Principal.UserId
+        logonType = $definition.Principal.LogonType
+        runLevel = $definition.Principal.RunLevel
+        actions = $actions
+        triggers = $triggers
+        settings = @{
+            multipleInstances = $definition.Settings.MultipleInstances
+            restartCount = $definition.Settings.RestartCount
+            restartInterval = $definition.Settings.RestartInterval
+            executionTimeLimit = $definition.Settings.ExecutionTimeLimit
+            startWhenAvailable = $definition.Settings.StartWhenAvailable
+            disallowStartIfOnBatteries = $definition.Settings.DisallowStartIfOnBatteries
+            stopIfGoingOnBatteries = $definition.Settings.StopIfGoingOnBatteries
+        }
+    }
+}
+
+function Get-RestorationXml {
+    param([string]$Xml, $TaskService)
+    if ([string]::IsNullOrWhiteSpace($Xml) -or
+        $Xml.Length -gt 524288) { throw 'TASK_RESTORATION_XML_UNVERIFIED: Invalid XML bounds.' }
+    $settings = [Xml.XmlReaderSettings]::new()
+    $settings.DtdProcessing = [Xml.DtdProcessing]::Prohibit
+    $settings.XmlResolver = $null
+    $settings.MaxCharactersInDocument = 524288
+    $text = [IO.StringReader]::new($Xml)
+    $reader = [Xml.XmlReader]::Create($text, $settings)
+    $document = [Xml.XmlDocument]::new()
+    $document.XmlResolver = $null
+    try { $document.Load($reader) }
+    finally { $reader.Dispose(); $text.Dispose() }
+    $namespace = 'http://schemas.microsoft.com/windows/2004/02/mit/task'
+    $root = $document.DocumentElement
+    if ($root.LocalName -cne 'Task' -or
+        $root.NamespaceURI -cne $namespace) { throw 'TASK_RESTORATION_XML_UNVERIFIED: Unexpected task root.' }
+    $registrations = @($document.SelectNodes("//*[local-name()='RegistrationInfo']"))
+    $descriptors = @($document.SelectNodes("//*[local-name()='SecurityDescriptor']"))
+    if ($registrations.Count -gt 1 -or
+        $descriptors.Count -gt 1) { throw 'TASK_RESTORATION_XML_UNVERIFIED: Duplicate registration metadata.' }
+    foreach ($registration in $registrations) {
+        if ($registration.NamespaceURI -cne $namespace -or
+            $registration.ParentNode -ne $root) { throw 'TASK_RESTORATION_XML_UNVERIFIED: Unexpected registration metadata.' }
+    }
+    foreach ($descriptor in $descriptors) {
+        if ($descriptor.NamespaceURI -cne $namespace -or
+            $descriptor.ParentNode.LocalName -cne 'RegistrationInfo' -or
+            $descriptor.ParentNode.NamespaceURI -cne $namespace -or
+            $descriptor.ParentNode.ParentNode -ne $root) { throw 'TASK_RESTORATION_XML_UNVERIFIED: Unexpected embedded descriptor.' }
+    }
+    $definition = $TaskService.NewTask(0)
+    $definition.XmlText = $Xml
+    $definition.RegistrationInfo.SecurityDescriptor = ''
+    return $definition.XmlText
+}
+
+function Get-MatchingTasks {
+    param($TaskFolder, [int]$Depth)
+    if ($Depth -gt 8) { throw 'Task folder depth exceeds the inspection bound.' }
+    $script:folderCount++
+    if ($script:folderCount -gt 512) { throw 'Task folder count exceeds the inspection bound.' }
+    foreach ($candidate in $TaskFolder.GetTasks(1)) {
+        $matching = $candidate.Name -in @("McpPacemaker-$Port", 'McpPacemaker')
+        foreach ($action in $candidate.Definition.Actions) {
+            if ($action.Type -eq 0 -and
+                $null -ne $action.Arguments -and
+                $action.Arguments.EndsWith("\autostart\windows\launcher.vbs`" $Port", [StringComparison]::OrdinalIgnoreCase)) {
+                $matching = $true
+            }
+        }
+        if ($matching) { $candidate }
+    }
+    foreach ($childFolder in $TaskFolder.GetFolders(0)) {
+        Get-MatchingTasks -TaskFolder $childFolder -Depth ($Depth + 1)
+    }
+}
+if ($FunctionsOnly) { return }
+$service = New-Object -ComObject Schedule.Service
+$service.Connect()
+if ($Operation -eq 'compare-restored') {
+    $text = [Console]::In.ReadToEnd()
+    if ($text.Length -gt 1048576) { throw 'Task operation input exceeds the supported bound.' }
+    $request = $text | ConvertFrom-Json
+    Assert-TaskSecurity -Actual $request.actual.security -Expected $request.original.security -RuntimeSid $request.original.userSid
+    $actualXml = Get-RestorationXml -Xml $request.actual.xml -TaskService $service
+    $originalXml = Get-RestorationXml -Xml $request.original.xml -TaskService $service
+    if ((Get-XmlHash -Xml $actualXml) -cne (Get-XmlHash -Xml $originalXml)) {
+        throw 'Restored legacy registration XML differs beyond its embedded descriptor representation.'
+    }
+    @{ equivalent = $true } | ConvertTo-Json -Compress
+    return
+}
+$folder = $service.GetFolder('\')
+$script:folderCount = 0
+$tasks = @(Get-MatchingTasks -TaskFolder $folder -Depth 0)
+if ($tasks.Count -gt 16) { throw 'Too many matching Pacemaker registrations.' }
+if ($Operation -eq 'inspect') {
+    ConvertTo-Json -InputObject @($tasks | ForEach-Object { Get-TaskRecord -Task $_ }) -Depth 8 -Compress
+    return
+}
+
+$text = [Console]::In.ReadToEnd()
+if ($text.Length -gt 1048576) { throw 'Task operation input exceeds the supported bound.' }
+$request = $text | ConvertFrom-Json
+if ($tasks.Count -ne 1) { throw 'Exactly one selected registration is required before mutation.' }
+$task = $tasks[0]
+$record = Get-TaskRecord -Task $task
+Assert-TaskSecurity -Actual $record.security -Expected $request.expected.security
+if ($record.name -ne $request.expected.name -or
+    $record.path -ne "\$($record.name)" -or
+    $record.xmlSha256 -cne $request.expected.xmlSha256 -or
+    $record.userSid -cne $currentSid -or
+    $record.logonType -ne 3 -or
+    $record.runLevel -ne 0) {
+    throw 'Selected task identity changed; no operation was performed.'
+}
+switch ($Operation) {
+    'hold' { $task.Enabled = $false }
+    'enable' { $task.Enabled = $true }
+    'repoint' {
+        if ($task.Enabled) { throw 'Registration must be held before replacing its launcher.' }
+        $launcher = [IO.Path]::GetFullPath($request.launcher)
+        if ($launcher.IndexOfAny([char[]]"`"`r`n") -ge 0 -or
+            -not [IO.File]::Exists($launcher)) { throw 'Invalid stable launcher path.' }
+        $definition = $task.Definition
+        if ($definition.Actions.Count -ne 1) { throw 'Unexpected task actions.' }
+        $definition.Actions.Item(1).Arguments = "`"$launcher`""
+        # Update only, do not alter principal ACEs, and suppress registration-trigger execution.
+        $definition.RegistrationInfo.SecurityDescriptor = ''
+        $folder.RegisterTaskDefinition($task.Name, $definition, 52, $definition.Principal.UserId, $null, 3, $null) | Out-Null
+    }
+    'restore' {
+        if ($task.Enabled) { throw 'Registration must be held before restoration.' }
+        Assert-TaskSecurity -Actual $record.security -Expected $request.original.security
+        $definition = $service.NewTask(0)
+        $definition.XmlText = $request.original.xml
+        if ((Get-XmlHash -Xml $request.original.xml) -cne $request.original.xmlSha256 -or
+            (Get-UserSid -User $definition.Principal.UserId) -cne $currentSid -or
+            $definition.Principal.LogonType -ne 3 -or
+            $definition.Principal.RunLevel -ne 0 -or
+            $request.original.name -ne $task.Name) { throw 'Invalid original task identity.' }
+        $definition.RegistrationInfo.SecurityDescriptor = ''
+        $folder.RegisterTaskDefinition($task.Name, $definition, 52, $definition.Principal.UserId, $null, 3, $null) | Out-Null
+    }
+    'start' { $task.Run($null) | Out-Null }
+}
+$updated = Get-TaskRecord -Task ($folder.GetTask($task.Name))
+Assert-TaskSecurity -Actual $updated.security -Expected $record.security
+$expectedDefinition = $service.NewTask(0)
+$expectedDefinition.XmlText = $record.xml
+switch ($Operation) {
+    'hold' { $expectedDefinition.Settings.Enabled = $false }
+    'enable' { $expectedDefinition.Settings.Enabled = $true }
+    'repoint' { $expectedDefinition.Actions.Item(1).Arguments = "`"$launcher`"" }
+    'restore' { $expectedDefinition.XmlText = $request.original.xml }
+}
+$updatedDefinition = $service.NewTask(0)
+$updatedDefinition.XmlText = $updated.xml
+if ($Operation -in @('repoint', 'restore')) {
+    $expectedDefinition.RegistrationInfo.SecurityDescriptor = ''
+    if (-not [string]::IsNullOrEmpty($updatedDefinition.RegistrationInfo.SecurityDescriptor)) {
+        throw 'Registration changed beyond the requested scoped edit; do not stop or activate a backend.'
+    }
+    $updatedDefinition.RegistrationInfo.SecurityDescriptor = ''
+}
+if ((Get-XmlHash -Xml $expectedDefinition.XmlText) -cne (Get-XmlHash -Xml $updatedDefinition.XmlText)) {
+    throw 'Registration changed beyond the requested scoped edit; do not stop or activate a backend.'
+}
+$updated | ConvertTo-Json -Depth 8 -Compress